package cz.muni.fi.pa165.musiclibrary.api.service;

import java.util.List;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import cz.muni.fi.pa165.musiclibrary.api.database.entity.IAlbum;
import cz.muni.fi.pa165.musiclibrary.api.database.entity.IArtist;
import cz.muni.fi.pa165.musiclibrary.api.database.entity.IGenre;
import cz.muni.fi.pa165.musiclibrary.api.service.dto.ISongDTO;

/**
*
* @author Martin Majlath
* 2012-11-03T00:06:23+0100
*/
public interface ISongService {

     /**
     * Create new song
     * 
     * @param song Song to be create.
     * @throws IllegalArgumentException If:
     * <ul>
     *  <li>parameter is {@code null},</li>
     *  <li>song identifier is <strong>not</strong> {@code null}.
     * </ul>
     */
    void create(final ISongDTO song);
    
    /**
     * Edit song
     *        
     * @param song Song to be updated.
     * @throws IllegalArgumentException If:
     * <ul>
     *  <li>parameter is {@code null},</li>
     *  <li>song identifier is {@code null}.
     * </ul>
     */
    void update(final ISongDTO song);
    
    /**
     * Deletes song
     * 
     * @param song Song to be deleted.
     * @throws IllegalArgumentException If:
     * <ul>
     *  <li>parameter is {@code null},</li>
     *  <li>song identifier is {@code null}.
     * </ul>
     */
    void delete(final ISongDTO song);
    
    /**
     * Returns a song with given identifier or {@code null} if there isn't one.
     * 
     * @param id Identifier.
     * @return Song or {@code null} if there is none for given identifier.
     * @throws IllegalArgumentException If given identifier is {@code null}.
     */
    @Nullable
    ISongDTO getById(final Long id);
    
    /**
     * Returns a list of all songs. Never returns {@code null}, if there are no 
     *  songs, returns empty list.
     * 
     * @return List of songs, never returns {@code null}.
     */
    @Nonnull
    List<ISongDTO> getAll();
    
    /**
     * Returns a list of all songs that are part of given album. Never returns 
     *  {@code null}, if there are no songs for given album, returns empty list.
     * 
     * @param album Album.
     * @return List of songs on given album, never returns {@code null}.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    @Nonnull
    List<ISongDTO> getByAlbum(final IAlbum album);
    
    /**
     * Returns a list of songs that have given artist assigned as author. 
     *  Never returns {@code null}, if there are no songs for given artist, 
     *  returns empty list.
     * 
     * @param artist Artist.
     * @return List of songs of given artist, never returns {@code null}.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    @Nonnull
    List<ISongDTO> getByArtist(final IArtist artist);
    
    /**
     * Returns a list of songs of given genre. Never returns {@code null}, 
     *  if there are no songs of given genre, returns empty list.
     * 
     * @param genre Genre.
     * @return List of songs of given genre, never returns {@code null}.
     * @throws IllegalArgumentException If parameter is {@code null}.
     */
    List<ISongDTO> getByGenre(final IGenre genre);
    
    /**
     * Returns a list of songs whose title contains given string. Never returns 
     *  {@code null}, if there are no such songs, returns empty list.
     * 
     * @param title String of characters to look for.
     * @return List of songs whose title contains given string, never returns 
     *  {@code null}.
     * @throws IllegalArgumentException If parameter is {@code null}
     */
    List<ISongDTO> getByTitle(final String title);
    
}